﻿using System;
using System.Threading.Tasks;

namespace Honest.MES.Contracts.Interfaces
{
    /// <summary>
    /// 所有后台服务的统一接口契约
    /// 定义服务的基本信息、生命周期、状态和能力
    /// 实现该接口的服务可通过模块化机制动态加载和管理
    /// </summary>
    public interface IServiceBase
    {
        /// <summary>
        /// 服务名称（唯一标识，建议使用 PascalCase）
        /// 示例："DatabaseService", "OpcUaCommunicationService"
        /// </summary>
        string Name { get; }

        /// <summary>
        /// 服务描述（用于 UI 显示或日志记录）
        /// </summary>
        string Description { get; }

        /// <summary>
        /// 服务版本号（语义化版本，如 1.0.0）
        /// 用于模块版本控制和热更新判断
        /// </summary>
        string Version { get; }

        /// <summary>
        /// 是否在应用程序启动时自动运行
        /// true：启动时自动调用 OnService()
        /// false：需手动启动
        /// </summary>
        bool AutoStart { get; }

        /// <summary>
        /// 当前服务是否处于激活运行状态
        /// 由服务内部维护，用于状态监控
        /// </summary>
        bool IsActive { get; }

        /// <summary>
        /// 服务优先级等级（数值越小，优先级越高）
        /// 用于控制服务启动/关闭顺序
        /// 建议范围：0 ~ 99
        /// </summary>
        int Level { get; }

        /// <summary>
        /// 启动延迟时间（单位：毫秒）
        /// 用于错峰启动，避免资源竞争
        /// 例如：数据库服务可设为 1000，OPC 服务设为 2000
        /// </summary>
        int DelayTime { get; }

        /// <summary>
        /// 服务是否具备发布事件的能力
        /// 用于 UI 或监控系统判断服务功能
        /// 可结合 IEventAggregator 使用
        /// </summary>
        bool CanPublish { get; }

        /// <summary>
        /// 服务是否具备订阅事件的能力
        /// 用于 UI 或监控系统判断服务功能
        /// 可结合 IEventAggregator 使用
        /// </summary>
        bool CanSubscribe { get; }

        // ========================================================
        // 生命周期方法
        // 所有方法应支持异步，避免阻塞主线程
        // ========================================================

        /// <summary>
        /// 启动服务（开启业务逻辑）
        /// 此方法在 InitService 之后调用
        /// 应实现核心业务逻辑的启动，如：
        /// - 启动监听线程
        /// - 连接设备或数据库
        /// - 开始数据采集
        /// </summary>
        /// <returns>异步任务</returns>
        Task OnService();

        /// <summary>
        /// 停止服务（暂停业务逻辑）
        /// 应安全停止所有运行中的任务
        /// 保持状态可恢复
        /// </summary>
        /// <returns>异步任务</returns>
        Task OffService();

        /// <summary>
        /// 初始化服务（配置加载、资源分配）
        /// 在应用程序加载模块时调用
        /// 用于：
        /// - 读取配置文件
        /// - 初始化变量
        /// - 分配内存或资源
        /// - 注册事件订阅（非启动业务）
        /// </summary>
        /// <returns>异步任务</returns>
        Task InitService();

        /// <summary>
        /// 重启服务
        /// 默认实现可为：OffService + 延迟 + OnService
        /// 可根据需要重写
        /// </summary>
        /// <returns>异步任务</returns>
        Task RestartService();

        /// <summary>
        /// 退出服务（释放资源，准备卸载）
        /// 在应用程序关闭或模块卸载前调用
        /// 必须确保：
        /// - 释放所有非托管资源
        /// - 关闭连接
        /// - 取消事件订阅
        /// - 清理临时数据
        /// </summary>
        /// <returns>异步任务</returns>
        Task ExitService();

        // ========================================================
        // 状态与监控
        // ========================================================

        /// <summary>
        /// 获取当前服务的运行状态信息
        /// 用于在 UI 状态栏或监控面板中显示
        /// 建议返回 JSON 或可读字符串
        /// 示例："运行中 | 连接数: 3 | 处理速率: 120条/秒"
        /// </summary>
        /// <returns>状态信息字符串</returns>
        string GetStatusInfo();
    }
}